<!DOCTYPE html>
<!--
File:      ui.html
Author:    Henry Feild
Date:      March 2013
Purpose:   Describes the CLRM UI API.

%%COPYRIGHT%%

Version: %%VERSION%%
-->
<html>
<head>
    <script src="js/external/jquery.min.js"></script>
    <script src="js/content-page.js"></script>
</head>
<body>

<div class="toc">
    <h2>Contents</h2>
    <ul>
      <!--   <li><a href="#ui">User Interface API (top)</a> -->
        <li><a href="#ui:standalone">Stand-Alone Application API</a>
            <ul>
                <li><a href="#ui:openWindow">api.ui.openWindow</a>
                <li><a href="#ui:getFaviconURL">api.ui.getFaviconURL</a>
                <li><a href="#ui:setMessageFlag">api.ui.setMessageFlag</a>
            </ul>
        <li><a href="#ui:crowdlogger">CrowdLogger Widget API</a>
        <li><a href="#ui:contentScripts">Content Scripts</a>
            <ul>
                <li><a href="#ui:contentScripts.registerContentScript">api.ui.contentScripts.&shy;registerContentScript</a>
                <li><a href="#ui:contentScripts.unregisterContentScript">api.ui.contentScripts.&shy;unregisterContentScript</a>
            </ul>
    </ul>
</div>

<h1>User Interface API</h1>
<p>
In the sections that follow, we assume that the CLRM API instance passed to your CLRM is named <code>api</code>.
</p>

<a name="standalone"></a>
<h2>Stand-Alone Application API</h2>
<p>
    We've listed some of the important functions below along with details,
    such as parameter descriptions, an overview of how the function works,
    and examples.
</p>
<br/>
<br/>
<a name="#openWindow"></a>
<div class="function">
    <div class="top-top top-tag"><a href="#">top</a></div>
    <div class="top-bottom top-tag"><a href="#">top</a></div>
    <h3><code>api.ui.openWindow</code></h3>
    <h4>Parameters</h4>
        <p>
        <ul>
            <li>{object} <code>options</code>
            <ul>  
                A map of options. The following are supported:
                <li>{string} <code>content</code> 
                    <ul>The HTML to go inside.</ul>
                <li>{object} <code>resources</code>
                    <ul>If 'contents' is set, then all CLRM 
                    resource placeholders will be replaced
                    using this map.</ul>
                <li>{string} <code>url</code>
                    <ul>The URL to load (overrides contents). If
                    neither contents nor url are provided,
                    an about:blank page is opened.</ul>
                <li>{string} <code>name</code>
                    <ul>The name of the window to open. This will replace any 
                    open windows with this name.</ul>
                <li>{string} specs
                    <ul>The window.open specs. See <a 
                    href="http://www.w3schools.com/jsref/met_win_open.asp">this
                    page</a> for details.</ul>
                <li>{object} <code>specsMap</code>
                    <ul>A map of specs. This is serialized into the
                    format "key1=value1,key2=value2,...". The
                    keys should be the same as those specified
                    in the specs string.</ul>
                <li>{function} <code>callback</code>
                    <ul>Invoked when the window has been created.</ul>
            </ul>
        </ul>
        </p>

    <h4>Description</h4>
    <p>
        Opens a window. If <code>url</code> is not specified, then a 
        CrowdLogger extension page named <code>blank.html</code> is opened
        (this allows greater control over the window than if 
        <code>about:blank</code> is opened). If <code>content</code> is
        provided, it is dereferenced using the provided 
        <code>resources</code> and loaded into the DOM of 
        <code>blank.html</code>. Once the window has been opened, 
        <code>callback</code> (if provided) is invoked with the window 
        object.
    </p>
</div>

<a name="getFaviconURL"></a>
<div class="function">
    <div class="top-top top-tag"><a href="#">top</a></div>
    <div class="top-bottom top-tag"><a href="#">top</a></div>
    <h3><code>api.ui.getFaviconURL</code></h3>
    <h4>Parameters</h4>
        <p>
            <ul>
                <li>{string} <code>url</code>
                    <ul>The URL of the page to get the favicon for.</ul>
                <li>{boolean} <code>shorten</code>
                    <ul>Default: true; uses just the domain of the URL.</ul>
            </ul>
        </p>

    <h4>Description</h4>
    <p>
        Gets the URL of the favicon associated with the given page 
        (<code>url</code>). The URL of the default favicon will be returned if no favicon is found. The generated URL is a browser resource and can only 
        access cached favicons.
    </p>
</div>


<a name="setMessageFlag"></a>
<div class="function">
    <div class="top-top top-tag"><a href="#">top</a></div>
    <div class="top-bottom top-tag"><a href="#">top</a></div>
    <h3><code>api.ui.setMessageFlag</code></h3>
    <h4>Parameters</h4>
        <p>
            None.
        </p>

    <h4>Description</h4>
    <p>
        Tells CrowdLogger that there is at least one CLRM with an important
        message. This causes an alert badge to be placed over the CrowdLogger
        toolbar icon and a notification at the top of the Status page asserting
        that one or more Apps or Studies have pending messages.
    </p>
    <p>
        The Status page displays messages from all CLRMs, whether or not there
        is a message alert pending using the <code>getMessage</code> method
        that each CLRM is required to have. If you have triggered the message
        flag, update your <code>getMessage</code> method to return the pending
        message.
    </p>


    <h4>Examples</h4>
    <p>
        Suppose we have a CLRM that periodically checks a server for messages.
        Upon receiving a new message, the code below will update the message
        to be displayed and notify CrowdLogger.
    </p>

<pre class="prettyprint">
var curMessage = 'No messages.';

// ...

// Saves the message and alerts users that a message is pending.
function onNewMessageFromServer(message){
    curMessage = message;
    clrmAPI.ui.setMessageFlag();
}

// This is the required getMessage method.
this.getMessage = function(){
    return curMessage;
};
</pre> 

</div>


<a name="crowdlogger"></a>
<h2>CrowdLogger Widget API</h2>

<a name="contentScripts"></a>
<h2>Content Scripts</h2>
<p>
If the need arises to log something user behavior that is not already available via <code><a href="#user">api.user</a></code> (e.g., scrolling or mouse movements) or if an App or Study module must modify the content of pages viewed by a user (e.g., re-rank search results), the Content Scripts API is a great resource.  A content script is a stringified, self-executing function that is injected into pages viewed by the user (we call these <i>content pages</i>). The function can interact with the page's DOM, but does not have direct access to any of a CLRM's core code. Rather, it must communicate via messages using the <code>sendMessage</code> function. This function allows data and callbacks to be passed to the CLRM. 
</p>

<a name="contentScripts.registerContentScript"></a>
<div class="function">
    <div class="top-top top-tag"><a href="#">top</a></div>
    <div class="top-bottom top-tag"><a href="#">top</a></div>
    <h3><code>api.ui.contentScripts.registerContentScript</code></h3>
    <h4>Parameters</h4>
        <p>
        <ul>
            <li>{object} <code>options</code></li>
            <span class="parameter-requirement">Required</span>
            <ul>  
                <li>{string} <code>script</code> 
                    <ul>The script to inject into each content page.</ul>
            </ul>
            <span class="parameter-requirement">Optional</span>
            <ul>
                <li>{function} <code>on_message</code>
                    <ul>
                        Invoked when the given content script invokes <code>sendMessage</code>. Should expect two arguments: <code>data</code> and <code>callback</code>. 
                    </ul>
                <li>{function} <code>on_success</code>
                    <ul>
                        Invoked when the script has been successfully registered.
                    </ul>
                <li>{function} <code>on_error</code>
                    <ul>
                        Invoked if there's an error.
                    </ul>
            </ul>
        </ul>
        </p>

    <h4>Description</h4>
    <p>
        Registers a content script to be injected into each content page when the page is loaded.
        The script has three global variables/functions at its disposal:
    </p>
        <ul>
            <li>{function} <code>sendMessage(msg, callback)</code>
                <ul>
                    Causes the optional <code>on_message</code> function to be invoked with <code>msg</code> as its only parameter. <code>msg</code> may be any serializable data type. <code>callback</code> option is optional, and if provided, is only valid for one-time use. It should only take one parameter, which can be anything serializable.
                </ul>
            <li>{string} <code>tabID</code>
                <ul>
                    The id of the tab in which the current page is loaded. This
                    may help link data collected with the content script and the data available in <code><a href="#user">api.user</a></code>.
                </ul>
            <li>{boolean} <code>focusedAtLoad</code>
                <ul>
                    Whether the page was focused when loaded.
                </ul>
        </ul>
</div>

<a name="contentScripts.unregisterContentScript"></a>
<div class="function">
    <div class="top-top top-tag"><a href="#">top</a></div>
    <div class="top-bottom top-tag"><a href="#">top</a></div>
    <h3><code>api.ui.contentScripts.unregisterContentScript</code></h3>
    <h4>Parameters</h4>
        <p>
        <ul>
            <li>{object} <code>options</code></li>
            <span class="parameter-requirement">Optional</span>
            <ul>
                <li>{function} <code>on_success</code>
                    <ul>
                        Invoked when the script is successfully unregistered.
                    </ul>
                <li>{function} <code>on_error</code>
                    <ul>
                        Invoked if there's an error.
                    </ul>
            </ul>
        </ul>
        </p>

    <h4>Description</h4>
    <p>
        Un-registers a content script. Any copies of the script injected into
     currently open pages will no longer be able to send messages (though
     they will continue to operate on those pages).
    </p>
</div>

</body>
</html>